Complete Kernel-managed Visa card checkout in CLI - #283

approving — the gating and validation look correct against the openapi spec, and the tests cover the important refusals. most of the findings are about agent steering: where guidance says "don't retry" or "stop" without a recovery path, and where the cli, the mcp server (kernel/kernel-mcp-server#238) and openapi disagree. i'd like the dead ends fixed here or in a fast follow, with #238 matched to the same wording.

dead ends (guidance that leaves the agent with no next step)

• cmd/vaults_help.go:15 (+ mcp #238 kernelVerificationGuidance) — "invoke it once" strands the agent if the response is lost. the api re-checks restart availability on every call and commits only if the item is unchanged, and restart is no longer listed once it succeeds. suggest: "if the result is unclear, re-read the item and invoke again only if restart_verification is still listed"
• cmd/vaults_help.go:15, cmd/vaults.go:290, cmd/vaults_output.go:451 — when restart isn't listed: "do not retry, delete, or replace; reconcile with support". delete returns 409 for a kernel card in recovery, so the agent and user have no next step. what should the user do to complete the purchase — a new card item under a new key on the same wallet? if that's safe for this recovery phase, say so with a "one more attempt after user confirmation" limit; if not, say what support does and what state the item ends in
• cmd/vaults_commands.go:237 (also :101, cmd/vaults_help.go:133, cmd/vaults_output.go:521, README) — "do not report or retry unknown outcomes, including transport loss". the server finishes after a client disconnect, and confirm_transaction is listed only when no report is in flight, none is recorded, and the item isn't in recovery. a provider rejection releases the claim, so the operation is listed again. suggest: "if the result is unclear, run items get; if confirm_transaction is still listed, the report wasn't recorded — send it once more; otherwise stop." mcp #238 has the same dead end
• same lines — "do not report unknown outcomes" gives no next step. confirm_transaction stays listed while the card is ready or expired and unreported, so: tell the user the outcome is unknown, and report it later once they see it (merchant email, order page, statement). also say when to use PENDING/ERROR and when to call an outcome "unknown"; as written, an agent looking at a "processing…" page can't tell, and the cautious choice is to never report
• cmd/vaults_output.go:528 — kernel wallet guidance always says "share the card_enrollment url". openapi: reconnect_required → the cardholder uses the new card_enrollment action; degraded → "the wallet must be deleted before adding another card". degraded needs its own guidance, e.g. "with user confirmation, delete this wallet and create a new one for one new enrollment". mcp #238 is also silent here
• cmd/vaults_output.go:558, cmd/vaults_help.go:20 — "wait for single_use_card.eligible" has no limit and no exit. reasons are network_token_<status> from the provider, and the README says ineligible can mean "pending or unsupported". say which reasons are terminal and give the path: enroll a different card through a new wallet, after user confirmation
• cmd/vaults_output.go:502 — the kernel card info line prints for every status, including declined, expired and consumed, where "Visa may require spend_approval… submit before expires_at" is misleading. the api allows deleting expired and declined cards, so: expired without submitting → if the user did submit, report first (confirm_transaction is still listed while expired); otherwise, with user confirmation, delete and create one new card item. declined → same, after the user picks a different card or merchant
• cmd/vaults_commands.go:425, cmd/vaults_help.go:126 — "cannot be updated" has three answers. openapi KernelCardVaultItemSpec: "delete and create a new item instead". this PR: "create a new card item for a new purchase" (dropped the old "delete the item and create a new one"). mcp #238: "inspect the existing item", which leaves no next step. suggest all three say: delete (if the api allows it) and create a new item, after user confirmation

cross-surface consistency

• cmd/vaults_help.go:15 vs mcp #238 kernelVerificationGuidance — mcp requires explicit user approval before restart_verification; cli doesn't mention approval
• cmd/vaults_help.go:15 — mirror the openapi wording: restart doesn't grant spend consent; the cardholder must verify and approve again on the new link
• cmd/vaults_commands.go:241,289, README.md:538,564, wallets get --open — --open on cardholder urls (card_enrollment, spend_approval) opens them on the machine running the cli. mcp #238 says "share privately with the cardholder, never open it for them". when an agent runs the cli, that opens the cardholder's capability url in the agent's own browser. pick one rule for both surfaces
• cmd/vaults.go:~340 — a confirm_transaction failure goes to util.CleanedUpSdkError with no next step. mcp #238's throwKernelVaultError separates "rejected (4xx): nothing new was authorized; fix inputs before another request" from uncertain failures. the cli should give the same per-error-class guidance
• cmd/vaults_commands.go:234 — openapi and mcp both say the currency "must match the approved purchase currency"; cli help only says "three uppercase letters"
• cmd/vaults_commands.go:203 vs mcp #238 — cli lists kernel fill fields as number, expiration (MM/YY or MM/YYYY), cvc, exp_month, exp_year; mcp lists number, expiration ("MM/YY"), cvc. align to what the api supports
• README.md:550 — the card spec example uses "currency":"usd" and the confirm example uses "USD". use "USD" in both so a copy-pasting agent doesn't think they differ

questions

• cmd/vaults_policy.go:32-40 vs cmd/vaults_output.go:41 — human output filters recovery operations, but -o json passes available_operations through unchanged. intentional? agents mostly read json

nits

• cmd/vaults.go:290-293 — "do not retry…" followed by "invoke restart_verification once" reads contradictory; consider a separate message for the listed case
• cmd/vaults.go:292, cmd/vaults_output.go:452 — len(actions.Operations) > 0 stands in for "restart listed"; an explicit check survives future recovery operations
• cmd/vaults_confirm_transaction.go:36-44 — the length check plus letter loop could be one ^[A-Z]{3}$ regexp, matching the openapi pattern word for word

follow-up (pre-existing, not this PR)

• cmd/vaults_commands.go:218 — "transport loss remains an uncertain outcome" for fill has no path. mcp #238 says to inspect the page and item state, then the field write is safe to retry. worth aligning in a separate PR